Developer Documentation

QuickTime 4 API Documentation

Inside Macintosh: QuickTime Components

Previous | Overview | Contents | Next |

Working With Channel Devices

Sequence grabbers provide a number of functions that allow applications to determine the devices that can be, or the device that is, attached to a given sequence grabber channel. These devices, in turn, allow the channel component to control the digitizing equipment. For example, video channels use video digitizer components, and sound channels use sound input drivers. Applications can use these functions to present a list of available devices to the user, allowing the user to select a specific device for each channel. The sequence grabber passes these functions on to your channel component.

The sequence grabber may use the SGGetChannelDeviceList function to retrieve a list of devices that may be used by your channel.

The sequence grabber can use the SGSetChannelDevice function to assign a device to your channel.

The SGGetChannelDeviceList function uses a device list structure to pass information about one or more channel devices. The SGDeviceListRecord data type defines the format of the device list structure.

typedef struct SGDeviceListRecord {
    short               count;                  /* count of devices */
    short               selectedIndex;          /* current device */
    long                reserved;               /* set to 0 */
    SGDeviceName        entry[1];               /* device names */
} SGDeviceListRecord, *SGDeviceListPtr, **SGDeviceList;
count
Indicates the number of devices described by this structure. The value of this field corresponds to the number of entries in the device name array defined by the entry field.

selectedIndex
Identifies the currently active device. The value of this field corresponds to the appropriate entry in the device name array defined by the entry field. Note that this value is 0-relative; that is, the first entry has an index number of 0, the second's value is 1, and so on.

reserved
Reserved for Apple. Always set to 0.

entry
Contains an array of device name structures. Each structure corresponds to one valid device. The count field indicates the number of entries in this array. The SGDeviceName data type defines the format of a device name structure; this data type is discussed next.

Device list structures contain an array of device name structures. Each device name structure identifies a single device that may be used by the channel. The SGDeviceName data type defines the format of a device name structure.

typedef struct SGDeviceName {
    Str63           name;                   /* device name */
    Handle          icon;                   /* device icon */
    long            flags;                  /* flags */
    long            refCon;                 /* set to 0 */
    long            reserved;               /* set to 0 */
} SGDeviceName;

Field descriptions

name
Contains the name of the device. For video digitizer components, this field contains the component's name as specified in the component resource. For sound input drivers, this field contains the driver name.

icon
Contains a handle to the device's icon. Some devices may support an icon, which applications may choose to present to the user. If the device does not support an icon, or if the sequence grabber chooses not to retrieve this information (by setting the sgDeviceListWithIcons flag to 0 when it calls the SGGetChannelDeviceList function, which is described in the next section), set this field to nil .

flags
Reflects the current status of the device. The following flag is defined:

sgDeviceNameFlagDeviceUnavailable
When set to 1, this flag indicates that this device is not currently available.

refCon
Reserved for Apple. Always set to 0.

reserved
Reserved for Apple. Always set to 0.

SGGetChannelDeviceList

The SGGetChannelDeviceList function allows the sequence grabber to retrieve a list of the devices that are valid for your channel.

pascal ComponentResult SGGetChannelDeviceList (SGChannel c,
                                         long selectionFlags,
                                         SGDeviceList *list);
c
Identifies the channel connection for this operation.

selectionFlags
Controls the data you are to return for each device. The following flags are defined:

sgDeviceListWithIcons
Specifies whether the sequence grabber wants to retrieve an icon for each device. If this flag is set to 1, return an icon for each device in the list, in the icon field. If this flag is set to 0, set the icon field to 0.

sgDeviceListDontCheckAvailability
Controls whether you verify that each device is currently available. If this flag is set to 1, do not check the availability of each device. Otherwise, you should check each device's availability, and set the sgDeviceNameFlagDeviceUnavailable flag appropriately in each device name structure that you return.

list
Contains a pointer to a device list structure pointer. The channel creates a device name structure and returns a pointer to that structure in the field referred to by this parameter. Applications use the sequence grabber's SGDisposeDeviceList function to dispose of the memory used by the list.

DESCRIPTION

This function allows the sequence grabber to retrieve a list of the devices that may be used by your channel. Each entry in this list identifies a valid device by name. Applications may then place these device names into a menu using the sequence grabber's SGAppendDeviceListToMenu function.

Applications may use this function in order to determine the device your channel is currently using. Be sure to set the selectedIndex field properly.

RESULT CODES

Memory Manager errors

SEE ALSO

You may use the sequence grabber's SGSortDeviceList function to sort the entries in your device list structure. This function is discussed on SGSortDeviceList .

SGSetChannelDevice

The SGSetChannelDevice function allows the sequence grabber to assign a device to your channel.

pascal ComponentResult SGSetChannelDevice (SGChannel c,
                                          StringPtr name);
c
Identifies the channel connection for this operation.

name
Contains a pointer to the device's name string. This name is contained in the name field of the appropriate device name structure in the device list that your channel returns to the SGGetChannelDeviceList function.

DESCRIPTION

When the sequence grabber calls your SGSetChannelDevice function, your channel should try to use the specified device instead of the device currently in use. The device name must be derived from your channel's device list.

RESULT CODES

paramErr

-50

Invalid parameter value

deviceCantMeetRequest

-9408

Device cannot support grabber

SEE ALSO

The sequence grabber obtains the device list by calling your SGGetChannelDeviceList function, which is discussed in the previous section.

© 1999 Apple Computer, Inc.

Previous | Overview | Contents | Next